home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / pull5xa.arc / PULLREF.DOC < prev    next >
Text File  |  1989-01-10  |  74KB  |  1,628 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                            MULTI-LEVEL PULL-DOWN MENUS
  21.                                  REFERENCE GUIDE
  22.  
  23.                                   Version 5.Xa
  24.                                 January 11, 1989
  25.  
  26.  
  27.                Copyright (C) 1987-1989 Eagle Performance Software
  28.                               All Rights Reserved.
  29.  
  30.  
  31.  
  32.                                _______                     
  33.                           ____|__     |               (tm) 
  34.                        --|       |    |------------------- 
  35.                          |   ____|__  |  Association of    
  36.                          |  |       |_|  Shareware         
  37.                          |__|   o   |    Professionals     
  38.                        -----|   |   |--------------------- 
  39.                             |___|___|    MEMBER            
  40.  
  41.  
  42.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  43.  
  44.  
  45.  
  46.                        T A B L E   O F   C O N T E N T S
  47.  
  48.         1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . 3
  49.              Purpose . . . . . . . . . . . . . . . . . . . . . . . 3
  50.              Fill-in-the-Blank . . . . . . . . . . . . . . . . . . 3
  51.  
  52.         2. PROCEDURES AND FUNCTIONS  . . . . . . . . . . . . . . . 4
  53.              CheckForPop . . . . . . . . . . . . . . . . . . . . . 4
  54.              CheckForPullDown  . . . . . . . . . . . . . . . . . . 4
  55.              CheckGlobalKeys . . . . . . . . . . . . . . . . . . . 4
  56.              DisplayFields . . . . . . . . . . . . . . . . . . . . 4
  57.              Enter . . . . . . . . . . . . . . . . . . . . . . . . 5
  58.              EnterSeq  . . . . . . . . . . . . . . . . . . . . . . 5
  59.              GetOverrideStats  . . . . . . . . . . . . . . . . . . 5
  60.              GetUserPullStats  . . . . . . . . . . . . . . . . . . 5
  61.              GotoKeyDispatcher . . . . . . . . . . . . . . . . . . 5
  62.              HelpKeyPressed  . . . . . . . . . . . . . . . . . . . 6
  63.              HiLiteRow . . . . . . . . . . . . . . . . . . . . . . 6
  64.              InitPull  . . . . . . . . . . . . . . . . . . . . . . 6
  65.              InRangeW  . . . . . . . . . . . . . . . . . . . . . . 6
  66.              Popped  . . . . . . . . . . . . . . . . . . . . . . . 6
  67.              PullDirectory . . . . . . . . . . . . . . . . . . . . 7
  68.              PullHelpWndw  . . . . . . . . . . . . . . . . . . . . 7
  69.              ReadKbd . . . . . . . . . . . . . . . . . . . . . . . 7
  70.              SetCmdSeq . . . . . . . . . . . . . . . . . . . . . . 7
  71.              ShowErrMsg  . . . . . . . . . . . . . . . . . . . . . 8
  72.              ShowMsg . . . . . . . . . . . . . . . . . . . . . . . 8
  73.              ShowTopLine . . . . . . . . . . . . . . . . . . . . . 8
  74.              StrSL . . . . . . . . . . . . . . . . . . . . . . . . 8
  75.              StrSR . . . . . . . . . . . . . . . . . . . . . . . . 9
  76.              TopKeyPressed . . . . . . . . . . . . . . . . . . . . 9
  77.              TurnArrows  . . . . . . . . . . . . . . . . . . . . . 9
  78.              WorkWndw  . . . . . . . . . . . . . . . . . . . . . . 9
  79.  
  80.         3. DATA STRUCTURE  . . . . . . . . . . . . . . . . . . . . 10
  81.              Configuration Constants . . . . . . . . . . . . . . . 10
  82.              Main Menu Declarations  . . . . . . . . . . . . . . . 11
  83.              Submenu Declarations  . . . . . . . . . . . . . . . . 16
  84.              Message Line Declarations . . . . . . . . . . . . . . 17
  85.              Help Window Declarations  . . . . . . . . . . . . . . 18
  86.              Data Window/Entry Declarations  . . . . . . . . . . . 20
  87.  
  88.         APPENDIX A:  MEMORY ALLOCATION . . . . . . . . . . . . . . 25
  89.              Global vs. Dynamic  . . . . . . . . . . . . . . . . . 25
  90.              Global Memory . . . . . . . . . . . . . . . . . . . . 25
  91.              Dynamic Memory  . . . . . . . . . . . . . . . . . . . 25
  92.              Code Size . . . . . . . . . . . . . . . . . . . . . . 26
  93.  
  94.         APPENDIX B:  ERROR MESSAGES  . . . . . . . . . . . . . . . 27
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.                                        2
  103.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  104.  
  105.  
  106.    1.  I N T R O D U C T I O N
  107.  
  108.  
  109.    PURPOSE
  110.  
  111.    This document is a technical reference manual describing each routine and 
  112.    variable in detail in a format similar to the TP manual.  The routines are 
  113.    described in alphabetical order.  Since this manual is on disk, you can 
  114.    find your interest easily with any search utility.
  115.  
  116.    Application - Because PULL uses QWIK and WNDW, all routines will perform in 
  117.    the following applications:
  118.  
  119.      . All video text modes - 0, 1, 2, 3 and 7.
  120.      . Any column mode - 40, 80, or variable.
  121.      . For IBM PC, XT, AT, PCjr, PC convertible, all PS/2 models, 3270 PC, and 
  122.        compatibles.
  123.      . With MDA, CGA, EGA, MCGA, VGA, 8214/A, all Hercules video cards.
  124.      . Perform routines in both absolute and window-relative coordinates.
  125.  
  126.    Please note that the demonstration files are set to work on an 80 column 
  127.    mode on video page 0 in a non-multi-tasking environment.  However, these 
  128.    can be changed with the source code.
  129.  
  130.  
  131.    FILL-IN-THE-BLANK
  132.  
  133.    Since most of PULL is based on the fill-in-the-blank concept for records, 
  134.    there are only a few procedures and functions that you would need to know 
  135.    about data entries and specialized programming of user windows.  Most of 
  136.    your interest will probably be in the Data Structure section that follows 
  137.    later, so you know which "blanks" you can fill.
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.    Chapter 1, Introduction                                             Page 3
  164.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  165.  
  166.  
  167.    2.  P R O C E D U R E S   A N D   F U N C T I O N S
  168.  
  169.    In this section, a detailed description is provided for each procedure and 
  170.    function.
  171.  
  172.  
  173.    ---------------------------------------------------------------------------
  174.    CheckForPop procedure                                                  Pull
  175.    ---------------------------------------------------------------------------
  176.    Function       Sets Pop true if menu(s) need to be removed.
  177.    Declaration    CheckForPop
  178.    Remarks        This procedure is primarily used in user windows that to 
  179.                   interface with the pull-down menus.  It analyzes the current 
  180.                   status of the menu control flags to see if one or more menus 
  181.                   need to be removed.
  182.    See also       CheckForPullDown
  183.    Example        See the User Window section in PULL5XA.DOC.
  184.  
  185.    ---------------------------------------------------------------------------
  186.    CheckForPullDown procedure                                             Pull
  187.    ---------------------------------------------------------------------------
  188.    Function       Displays help message, reads keyboard input, and permits 
  189.                   background processing while keyboard is idle.
  190.    Declaration    CheckForPullDown (MsgLineNum: byte)
  191.    Remarks        This procedure is primarily used in user windows that to 
  192.                   interface with the pull-down menus.  It analyzes the current 
  193.                   status of the menu control flags to see if it has reached 
  194.                   its destination menu/window.  If WaitForKbd is false when 
  195.                   entering this procedure, it will assume that Key and ExtKey 
  196.                   are set correctly and not wait for the keyboard input for 
  197.                   just one pass.  ReadKbd and KbdIdle are subroutines.
  198.    Example        See the User Window section in PULL5XA.DOC.
  199.    See also       CheckForPop, KbdIdle, ReadKbd
  200.  
  201.    ---------------------------------------------------------------------------
  202.    CheckGlobalKeys procedure                                          PullStat
  203.    ---------------------------------------------------------------------------
  204.    Function       Provides a case of global keystrokes to access any part 
  205.                   of the program at any time.
  206.    Declaration    Called indirectly by PULL.
  207.    Remarks        Global keys can be any extended key.  The contents are 
  208.                   optional, but the procedure must exist.  You must include 
  209.                   PullStat in at least on USES statement in the program even 
  210.                   though it can compile without it.
  211.    See also       GetUserPullStats, GetOverrideStats
  212.  
  213.    ---------------------------------------------------------------------------
  214.    DisplayFields procedure                                                Pull
  215.    ---------------------------------------------------------------------------
  216.    Function       Displays the contents of a sequence of data entry fields 
  217.                   given the first and last record numbers.
  218.    Declaration    DisplayFields (First,Last: word)
  219.    Remarks        Fields are displayed in window-relative coordinates.
  220.    See also       Enter, EnterSeq
  221.  
  222.  
  223.  
  224.    Chapter 2, Procedures and Functions                                 Page 4
  225.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  226.  
  227.  
  228.    ---------------------------------------------------------------------------
  229.    Enter procedure                                                        Pull
  230.    ---------------------------------------------------------------------------
  231.    Function       Edits a field for a single data entry given the Data Entry 
  232.                   record.
  233.    Declaration    Enter (RecNum: word);
  234.    Remarks        This procedure is used if you want to customize your own 
  235.                   sequence of entry.  RecNum is the record number of the data 
  236.                   entry.  This procedure only shows the string being edited 
  237.                   for input.  For output display, use DisplayFields.
  238.    See also       DisplayFields, EnterSeq
  239.  
  240.    ---------------------------------------------------------------------------
  241.    EnterSeq procedure                                                     Pull
  242.    ---------------------------------------------------------------------------
  243.    Function       Edits a sequence of fields for data entry given the Data 
  244.                   Entry records.
  245.    Declaration    EnterSeq (First,Last: word; VAR Start: word);
  246.    Remarks        This procedure handles full editing of a sequence of data 
  247.                   entries handled by smart HiLite algorithms.  The sequence of 
  248.                   entry is the order of DataEntryNames in PULLDATA.PAS.  
  249.                   First/Last are the first and last record numbers in the 
  250.                   sequence.  Start is where you want the HiLite to start, and 
  251.                   keeps up with the current record.  Use DisplayFields once 
  252.                   before editing.
  253.    See also       DisplayFields, Enter
  254.  
  255.    ---------------------------------------------------------------------------
  256.    GetOverrideStats procedure                                         PullStat
  257.    ---------------------------------------------------------------------------
  258.    Function       Overrides any default configurations set by GetUserPullStats 
  259.                   and InitPull.
  260.    Declaration    Called indirectly by PULL.
  261.    Remarks        If you have any exceptions for your menu records, place your 
  262.                   assignments in this procedure.  The contents are optional, 
  263.                   but the procedure must exist.  You must include PullStat in 
  264.                   at least one USES statement in the program even though it 
  265.                   can compile without it.
  266.    See also       CheckGlobalKeys, GetUserPullStats
  267.  
  268.    ---------------------------------------------------------------------------
  269.    GetUserPullStats procedure                                         PullStat
  270.    ---------------------------------------------------------------------------
  271.    Function       Initializes all menus, windows and message lines for the 
  272.                   pull-down environment.
  273.    Declaration    Called indirectly by PULL.
  274.    Remarks        You must include the PullStat in at least one USES statement 
  275.                   in the program even though it can compile without it.
  276.    See also       CheckGlobalKeys, GetOverrideStats
  277.  
  278.    ---------------------------------------------------------------------------
  279.    GotoKeyDispatcher procedure                                            Pull
  280.    ---------------------------------------------------------------------------
  281.    Function       Turns control over to PULL.
  282.    Declaration    GotoKeyDispatcher
  283.  
  284.  
  285.    Chapter 2, Procedures and Functions                                 Page 5
  286.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  287.  
  288.  
  289.    Remarks        This procedure is called by your main program after all the 
  290.                   data record have been initialized.
  291.    Example        See PULLDEMO.PAS.
  292.  
  293.    ---------------------------------------------------------------------------
  294.    HelpKeyPressed function                                                Pull
  295.    ---------------------------------------------------------------------------
  296.    Function       Trivial function returns true if the context-sensitive help 
  297.                   key has been pressed.
  298.    Declaration    HelpKeyPressed
  299.    Result type    boolean
  300.    Remarks        PULL is currently assigned the F1 key for the help window.
  301.    See also       TopKeyPressed, PullHelpWndw
  302.  
  303.    ---------------------------------------------------------------------------
  304.    HiLiteRow procedure                                                    Pull
  305.    ---------------------------------------------------------------------------
  306.    Function       Highlights a line in a menu.
  307.    Declaration    HiLiteRow (Row: byte; Attr: integer)
  308.    Remarks        This procedure can be used in any user menu to show the 
  309.                   HiLite bar by simply changing the attribute.  Row is a 
  310.                   window-relative row and Attr is the attribute for the 
  311.                   HiLite.
  312.  
  313.    ---------------------------------------------------------------------------
  314.    InitPull procedure                                                     Pull
  315.    ---------------------------------------------------------------------------
  316.    Function       Initializes WNDW and PULL records.
  317.    Declaration    InitPull (Attr: integer; ClearScr: boolean)
  318.    Remarks        Attr is the attribute of Window0 and is also assigned to the 
  319.                   global variable InitAttr.  If ClearScr is true, it will 
  320.                   clear the screen which is not necessary for PermMode 
  321.                   windows.  This procedure is required and is only used once.
  322.  
  323.    ---------------------------------------------------------------------------
  324.    InRangeW function                                                      Pull
  325.    ---------------------------------------------------------------------------
  326.    Function       Returns true if a word test value is between the high and 
  327.                   low limits inclusive.
  328.    Declaration    InRangeW (Low,Value,High: word)
  329.    Result type    boolean
  330.    Remarks        The function will swap Low and High before testing if they 
  331.                   are not in the correct order.
  332.    Restrictions   Negative values cannot be used.
  333.  
  334.    ---------------------------------------------------------------------------
  335.    Popped function                                                        Pull
  336.    ---------------------------------------------------------------------------
  337.    Function       Used to detect if all menus have all been removed before 
  338.                   executing menu procedures.
  339.    Declaration    Popped
  340.    Result type    boolean
  341.    Remarks        This function is used in procedures called by the menu 
  342.                   ProcPtr.  PULL executes the ProcPtr procedure twice when 
  343.                   Popped is used.  It sets several flags for you including 
  344.  
  345.  
  346.    Chapter 2, Procedures and Functions                                 Page 6
  347.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  348.  
  349.  
  350.                   PopAndProcess.  The first time Popped is tested it returns 
  351.                   false and sets the appropriate flags.  When the menus are 
  352.                   removed and ProcPtr is executed again, Popped will be true.  
  353.                   This allows your statement to read like plain English.
  354.    Example        This far procedure is called by a ProcPtr in a menu:
  355.  
  356.                     procedure MyProc;
  357.                     begin
  358.                       if Popped then DoMyProc;
  359.                     end;
  360.  
  361.    ---------------------------------------------------------------------------
  362.    PullDirectory procedure                                             PullDir
  363.    ---------------------------------------------------------------------------
  364.    Function       Displays the contents of the current disk directory.
  365.    Declaration    PullDirectory (VAR NameToChange: FileNameStr;
  366.                                      NameToHiLite: FileNameStr);
  367.    Remarks        Pressing RETURN on the HiLited item will be assigned to 
  368.                   NameToChange.  If NameToHiLite is given, the menu will be 
  369.                   displayed initially with the HiLite centered in the menu on 
  370.                   NameToHiLite.  If NameToHiLite is null, the HiLite will just 
  371.                   be centered on the first page.
  372.    Example        See PULLSTAT.PAS for PULLDEMO.PAS.
  373.  
  374.    ---------------------------------------------------------------------------
  375.    PullHelpWndw procedure                                                 Pull
  376.    ---------------------------------------------------------------------------
  377.    Function       Displays a context-sensitive help window.
  378.    Declaration    PullHelpWindow (WndwNum: byte);
  379.    Remarks        This procedure can be used in any procedure where keyboard 
  380.                   input is tested.  WndwNum is the HelpWndw record number, but 
  381.                   using the ordinal value of HelpWndwNames is easier to use.
  382.    See also       HelpKeyPressed
  383.  
  384.    ---------------------------------------------------------------------------
  385.    ReadKbd procedure                                                      Pull
  386.    ---------------------------------------------------------------------------
  387.    Function       Reads keyboard input and permits background processing while 
  388.                   keyboard is idle.
  389.    Declaration    ReadKbd (VAR ExtKey: boolean; VAR Key: char);
  390.    Remarks        ExtKey is true if the key is extended.  Key is the character 
  391.                   of the key entered.  In addition, holding down the Alt key 
  392.                   will display the global key combination message.  Also, 
  393.                   while the keyboard is idle, the KbdIdle procedure is being 
  394.                   continually executed.
  395.    See also       CheckForPullDown, KbdIdle
  396.  
  397.    ---------------------------------------------------------------------------
  398.    SetCmdSeq procedure                                                    Pull
  399.    ---------------------------------------------------------------------------
  400.    Function       Sets PULL control flags to shortest path to the new menu.
  401.    Declaration    SetCmdSeq (NewCmdSeq: SeqStr)
  402.    Remarks        NewCmdSeq is the sequence of command letters pressed after 
  403.                   F10 to arrive at a new menu or window.  NewCmdSeq and the 
  404.                   current position, CmdSeq, are compared to create an new path 
  405.  
  406.  
  407.    Chapter 2, Procedures and Functions                                 Page 7
  408.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  409.  
  410.  
  411.                   by setting MoreCmdSeq and PopLevels.
  412.  
  413.    ---------------------------------------------------------------------------
  414.    ShowErrMsg procedure                                                   Pull
  415.    ---------------------------------------------------------------------------
  416.    Function       Shows an error message on the message line.
  417.    Declaration    ShowErrMsg (ErrMsgNum: word);
  418.    Remarks        ErrMsgNum is the index of the ErrMsgLine to display.  It is 
  419.                   easier to use the ordinal value of ErrMsgNames to identify 
  420.                   the message to display.  This message is usually used by 
  421.                   data entry routines.  After pressing ESC to acknowledge the 
  422.                   message, the original message is restored.
  423.    See also       ShowMsg
  424.    Example        Show the error message line named MyErrMsg:
  425.  
  426.                     ShowErrMsg (ord(MyErrMsg));
  427.  
  428.    ---------------------------------------------------------------------------
  429.    ShowMsg procedure                                                      Pull
  430.    ---------------------------------------------------------------------------
  431.    Function       Shows a message on the message line.
  432.    Declaration    ShowMsg (MsgNum: byte)
  433.    Remarks        MsgNum is the index of the MsgLine to display.  It is easier 
  434.                   to use the ordinal value of MsgLineNames to identify the 
  435.                   message to display.
  436.    See also       CheckForPullDown, ShowErrMsg
  437.    Example        Show the message line named MyMsg:
  438.  
  439.                     ShowMsg (ord(MyMsg));
  440.  
  441.  
  442.    ---------------------------------------------------------------------------
  443.    ShowTopLine procedure                                                  Pull
  444.    ---------------------------------------------------------------------------
  445.    Function       Simply displays the unhighlighted Top Line Menu.
  446.    Declaration    ShowTopLine
  447.    Remarks        This procedure is used to initially display the Top Line 
  448.                   menu for the screen design in PULLWORK.PAS or PULLSHEL.PAS.  
  449.                   It writes the string TopLineStr to the screen which is 
  450.                   assembled by InitPull.
  451.  
  452.    ---------------------------------------------------------------------------
  453.    StrSL function                                                         Pull
  454.    ---------------------------------------------------------------------------
  455.    Function       Returns a string left justified in a field of spaces.
  456.    Declaration    StrSL (S: string; Field: byte)
  457.    Result type    string
  458.    Remarks        If Field is less than the length of the string, the string 
  459.                   is simply returned.
  460.    See also       StrSR
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.    Chapter 2, Procedures and Functions                                 Page 8
  469.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  470.  
  471.  
  472.    ---------------------------------------------------------------------------
  473.    StrSR function                                                         Pull
  474.    ---------------------------------------------------------------------------
  475.    Function       Returns a string right justified in a field of spaces.
  476.    Declaration    StrSR (S: string; Field: byte)
  477.    Result type    string
  478.    Remarks        If Field is less than the length of the string, the string 
  479.                   is simply returned.
  480.    See also       StrSL
  481.  
  482.    ---------------------------------------------------------------------------
  483.    TopKeyPressed function                                                 Pull
  484.    ---------------------------------------------------------------------------
  485.    Function       Trivial function returns true if the top line menu key has 
  486.                   been pressed.
  487.    Declaration    TopKeyPressed
  488.    Result type    boolean
  489.    Remarks        PULL is currently assigned the F10 key for the top line 
  490.                   menu.
  491.    See also       HelpKeyPressed
  492.  
  493.    ---------------------------------------------------------------------------
  494.    TurnArrows procedure                                                   Pull
  495.    ---------------------------------------------------------------------------
  496.    Function       Displays or removes arrows on the highlighted line of a 
  497.                   menu that pulls down a submenu or user window.
  498.    Declaration    TurnArrows (Switch: Toggle)
  499.    Remarks        This procedure is used primarily to interface with user 
  500.                   windows that require the arrows to be turned on or off.
  501.    Example        See the User Window section in PULL5XA.DOC.
  502.  
  503.    ---------------------------------------------------------------------------
  504.    WorkWndw procedure                                                 PullWork
  505.    ---------------------------------------------------------------------------
  506.    Function       Provides a case of steps for the work window as the main 
  507.                   part of the program.
  508.    Declaration    Called indirectly by PULL.
  509.    Remarks        The contents are optional, but the procedure must exist.  
  510.                   You must include PullWork in the USES statement of the main 
  511.                   program even though it can compile without it.
  512.    Example        See PULLSHEL.PAS and PULLDEMO.PAS.
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.    Chapter 2, Procedures and Functions                                 Page 9
  530.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  531.  
  532.  
  533.    3.  D A T A   S T R U C T U R E
  534.  
  535.    This section will help describe the data structure of PULL and how it can 
  536.    be adjusted.  The variables in P5X-VAR.INC are allocated according to the 
  537.    conditional directives and constants set at the beginning of the file.  
  538.    There are several basic variables, but if desired, there are additional 
  539.    variables for virtual windows and multiple video pages.  Please refer to 
  540.    the source code in P5X-VAR.INC for the exact listing.
  541.  
  542.  
  543.    CONFIGURATION CONSTANTS
  544.  
  545.    These constants configure the size of the data structure.  If you have the 
  546.    complete source code, the constants can be trimmed to fit the requirements 
  547.    of your application program.  While developing the program, you can balloon 
  548.    these values so that PULL does not need to be recompiled every time the 
  549.    program expands.
  550.  
  551.      Constant          Value  Description
  552.      ----------------  -----  ------------------------------------------------
  553.      NumOfMainMenus    1-255  Sets the maximum number of main menu records to 
  554.                               be held in the heap.
  555.  
  556.      NumOfSubMenus     1-255  Sets the maximum number of submenu records to be 
  557.                               held in the heap.
  558.  
  559.      MaxMenuLines      1-253  Sets the maximum number of menu lines in each 
  560.                               menu record.
  561.  
  562.      MaxCharsPerLine   1-247  Sets the maximum number of characters per line 
  563.                               in all menu lines.  It also limits the size of 
  564.                               the title for the data windows.
  565.  
  566.      NumOfDataWndws    1-255  Sets the maximum number of data window records 
  567.                               to be held in the heap.
  568.  
  569.      NumOfDataEntries  1-255  Sets the maximum number of data entry records to 
  570.                               be held in the heap.
  571.  
  572.      DataStrSize       1-255  Sets the maximum number of characters that can 
  573.                               be entered in a data entry of any kind.
  574.  
  575.      NumOfHelpWndws    1-255  Sets the maximum number of help window records 
  576.                               to be held in global data.
  577.  
  578.      TotalHelpLines    1-255  Sets the maximum number of help lines in the 
  579.                               HelpLine array.  A greater number of lines can 
  580.                               be used if TP5 enumerated types are not used for 
  581.                               the index. 
  582.  
  583.      HelpCharsPerLine  1-241  Sets the maximum number of characters per line 
  584.                               in all help windows.  Remember this excludes the 
  585.                               two extra spaces between border and text.
  586.  
  587.      NumOfMsgLines     1-255  Sets the maximum number of message lines to be 
  588.  
  589.  
  590.    Chapter 3, Data Structure                                           Page 10
  591.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  592.  
  593.  
  594.                               allocated in the MsgLine array.
  595.  
  596.      CrtStrSize        1-255  Sets the maximum number of characters that can 
  597.                               appear on a CRT.
  598.  
  599.      NumOfErrMsgLines  1-up   Sets the maximum number of message lines to be 
  600.                               allocated in the ErrMsgLine array.
  601.  
  602.      ErrStrSize        1-255  Sets the maximum number of characters in a 
  603.                               single ErrStrLine message.  This is usually less 
  604.                               than CrtStrSize, but cannot be greater.
  605.  
  606.  
  607.    MAIN MENU DECLARATIONS
  608.  
  609.    The following types, variables and constants are used for primarily for the 
  610.    main menus.  The variables are described in the order of their appearance 
  611.    in the file P5X-VAR.INC.
  612.  
  613.  
  614.    Types - These types are used to structure variables for the main menus:
  615.  
  616.      Type          Description
  617.      ------------  -----------------------------------------------------------
  618.      MenuModeType  This enumerated type gives a name for three different menu 
  619.                    modes.  Each mode controls how each line will interact with 
  620.                    the other lines.
  621.  
  622.                      Name            Description
  623.                      --------------  --------------------------------------
  624.                      ExecChoice      Executes the procedures indicated by 
  625.                                      ProcPtr and does not interact with the 
  626.                                      other menu lines.  This is the default.
  627.                      SingleChoice    Flags only the selected line in the menu 
  628.                                      and turns off all other flags.  If 
  629.                                      ProcPtr is not nil, it will also execute 
  630.                                      the procedure before flagging.
  631.                      MultipleChoice  Toggles the flag on any line in the menu.  
  632.                                      If ProcPtr is not nil, it will also 
  633.                                      execute the procedure before flagging.
  634.  
  635.      LineModeType  This enumerated type gives a name for seven different line 
  636.                    modes for any one line in the menu.
  637.  
  638.                      Name        Description
  639.                      ----------  ------------------------------------------
  640.                      Choice      Interacts with the rest of the menu 
  641.                                  according to the given menu mode.
  642.                      ExecOnly    Only executes ProcPtr and ignores flagging.
  643.                      Comment     Places text on the line with a different 
  644.                                  attribute and passed by the highlight.
  645.                      Partition   Places a horizontal border through the menu 
  646.                                  and is passed by the highlight.
  647.                      ToDataWndw  Places a dot symbol on the line and pulls 
  648.                                  down a data entry window.
  649.  
  650.  
  651.    Chapter 3, Data Structure                                           Page 11
  652.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  653.  
  654.  
  655.                      ToSubMenu   Places a three-bar symbol on the line and 
  656.                                  pulls down a submenu.
  657.                      ToUserWndw  Places a three-bar symbol on the line and 
  658.                                  executes ProcPtr.
  659.  
  660.      ProcPtrType   This is the type established for procedure pointers and is 
  661.                    a generic pointer type.
  662.  
  663.      Toggle        This enumerated type is just a practical way of 
  664.                    understanding the source code to indicate the common binary 
  665.                    conditions of On/Off and Yes/No.
  666.  
  667.      CrtStrType    Combined with CrtStrSize, this type will limit the size of 
  668.                    strings needed to display data onto the screen.  It is 
  669.                    usually used for message lines.
  670.  
  671.      SeqStrType    This type is used for strings that keep a record of the 
  672.                    command sequence.  Since the sequence is not greater than 
  673.                    the number of windows on the screen at any one time, 
  674.                    Wndw.MaxWndw is used.
  675.  
  676.      MenuRec       This record is used to fully describe any menu.  Each field 
  677.                    is worth describing.
  678.  
  679.                      Title - For main menus, this name will appear on the Top 
  680.                      Line menu.
  681.  
  682.                      CmdLtrs - InitPull assigns the first letter of each menu 
  683.                      line to be its corresponding command letter.  This string 
  684.                      keeps these assignments in sequence so that the line 1 
  685.                      letter is position 1, line 2 is position 2, etc.
  686.  
  687.                      Line - This is the array of the actual text that will 
  688.                      appear on each menu line.  The default is ''.
  689.  
  690.                      LineMode - This array is the line mode corresponding to 
  691.                      each line.  The default is Choice.
  692.  
  693.                      Flagged - This array is the status of the boolean flag 
  694.                      corresponding to each line.  The default is false.
  695.  
  696.                      LinkNum - This array has the byte value of submenu or 
  697.                      data window names of records to be linked.  The default 
  698.                      is 0.
  699.  
  700.                      ProcPtr - This array has the pointers for executing far 
  701.                      procedures when the menu line is selected.  The default 
  702.                      is nil which executes nothing.
  703.  
  704.                      ParentDir - This is the linking direction assigned to the 
  705.                      parent menu of this menu (which would be a submenu).  For 
  706.                      main menus, this value is NoDir.
  707.  
  708.                      LinkDir - This is the linking direction assigned to all 
  709.                      submenus on this menu which is determined by InitPull.
  710.  
  711.  
  712.    Chapter 3, Data Structure                                           Page 12
  713.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  714.  
  715.  
  716.  
  717.                      MenuMode - This is the menu mode.
  718.  
  719.                      MenuLines - This is the number of lines contained in this 
  720.                      menu and is determined by InitPull.
  721.  
  722.                      NameCol - For main menus, this is the column that the 
  723.                      HiLite is to appear on the Top Line menu which would 
  724.                      highlight the title.
  725.  
  726.                      Row .. Cols - These variables locate and size the window 
  727.                      for the menu.
  728.  
  729.                      DefaultLine - This is the line to be highlighted when the 
  730.                      program first starts.
  731.  
  732.                      HiLiteLine - This is the current position of the HiLite 
  733.                      on this menu.
  734.  
  735.                      SingleFlagLine - This is the line that has the only flag 
  736.                      in SingleChoice menu mode.
  737.  
  738.                      The following variables control the attributes in the 
  739.                      menus.  SameAttr is not permitted.
  740.  
  741.                        Battr - Border
  742.                        Wattr - entire Window contents
  743.                        Hattr - HiLite
  744.                        Lattr - command Letter
  745.                        Cattr - Comment line
  746.  
  747.                      Border - This is the border style used for the menu.
  748.  
  749.                      BackToDefault - If true, the HiLite will return to the 
  750.                      DefaultLine every time the menu is pulled down.  The 
  751.                      default is false.
  752.  
  753.                      Changed - PULL will toggle this to true if any of the 
  754.                      flags have been altered.  It is up to the programmer to 
  755.                      reset it to false if it is needed.
  756.  
  757.                      MsgLineNum - This is the index number of the MsgLine to 
  758.                      be displayed concurrently with this menu.
  759.  
  760.                      HelpWndwNum - This is the index number of the HelpWndw 
  761.                      record to be displayed for this menu when context-
  762.                      sensitive help is requested.
  763.  
  764.      MenuRecs      This array allocates the total number of main menu records 
  765.                    needed for the heap.  They do not all have to be used.
  766.  
  767.  
  768.    Variables - The following are the global variables used to create and 
  769.    control the pull-down menus:
  770.  
  771.  
  772.  
  773.    Chapter 3, Data Structure                                           Page 13
  774.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  775.  
  776.  
  777.      Variable      Description
  778.      ------------  -----------------------------------------------------------
  779.      MainMenu      (Type: ^MenuRecs) This is the pointer of the array of main 
  780.                    menu records in the heap.
  781.  
  782.      TopMenu       (Type: MenuRec)  As each menu record is accessed, main menu 
  783.                    or submenu, a copy of the record is made in TopMenu to 
  784.                    increase speed and save code.  The record is saved back in 
  785.                    the heap after use.
  786.  
  787.      MRI           (Type: word)  When a menu is copied into TopMenu, the array 
  788.                    index of the record is saved in this variable for later 
  789.                    reference.
  790.  
  791.      LastMainMenu  (Type: byte)  This is the index of the last main menu 
  792.                    displayed on the far right of the Top Line menu.  It is 
  793.                    <=NumOfMainMenus.
  794.  
  795.      TopLineStr    (Type: CrtStrType)  This is the actual string that appears 
  796.                    as the Top Line menu when ShowTopLine is used.
  797.  
  798.      TopLineRow    (Type: byte) This is the row on which TopLineStr appears.
  799.  
  800.      MainMenuRow   (Type: byte) This is the row on which the top border of the 
  801.                    main menus appears.
  802.  
  803.  
  804.    Attributes - The following variables control the default attributes and 
  805.    border in all the main menus and the top line menu.  SameAttr is not 
  806.    permitted in byte types.
  807.  
  808.      Name           Type      Description
  809.      -------------  --------  -------------------------------------
  810.      InitAttr       integer   base screen, set by Attr in InitPull.
  811.      TopLineAttr    byte      top line menu.
  812.      TopLineHattr   byte      HiLite on top line menu.
  813.      TopLineLattr   byte      command Letters on top line menu.
  814.      MainMenuWattr  byte      entire Window contents.
  815.      MainMenuBattr  byte      main menu Border.
  816.      MainMenuHattr  byte      HiLite in main menu.
  817.      MainMenuLattr  byte      command Letters in main menu.
  818.      MainMenuCattr  byte      Comment line.
  819.      MainMenuBrdr   Borders   main menu Border style.
  820.  
  821.  
  822.    Keyboard - The following variables and constant contain the last keyboard 
  823.    input from ReadKbd or CheckForPullDown.
  824.  
  825.      Variable      Description
  826.      ------------  -----------------------------------------------------------
  827.      Key           (Type: char) Contains the key code of the input.
  828.  
  829.      ExtKey        (Type: boolean) Set true if extended key.
  830.  
  831.      WaitForKbd    (Type: boolean = true) This typed constant causes a wait 
  832.  
  833.  
  834.    Chapter 3, Data Structure                                           Page 14
  835.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  836.  
  837.  
  838.                    for keyboard input when executing CheckForPullDown.  If it 
  839.                    is false, then the current values of Key and ExtKey are 
  840.                    considered valid and execution continues.
  841.  
  842.  
  843.    Control Flags - The following variables programmably control the pull-down 
  844.    menus in lieu of the end user.
  845.  
  846.      Variable      Description
  847.      ------------  -----------------------------------------------------------
  848.      PullDown      (Type: boolean)  When set true, the menus will be pulled 
  849.                    down from their current position according to the sequence 
  850.                    in MoreCmdSeq.
  851.  
  852.      Pop           (Type: boolean)  This flag is controlled by CheckForPop and 
  853.                    sets it true if the program needs to pop out of the current 
  854.                    menu.
  855.  
  856.      PopToWorkWndw (Type: boolean)  If true, the menus will all pop and return 
  857.                    control to the work window.
  858.  
  859.      PopToTop      (Type: boolean)  If true, control is set to highlight the 
  860.                    Top Line menu.
  861.  
  862.      PopAndProcess (Type: boolean)  This flag is controlled by the Popped 
  863.                    function to execute a ProcPtr in the menus after all the 
  864.                    menus have been popped.
  865.  
  866.      PopLevels     (Type: byte)  This flag is controlled by SetCmdSeq or can 
  867.                    be used manually.  It simply pops the number of levels of 
  868.                    menus/windows.
  869.  
  870.      Quit          (Type: boolean = false)  This typed constant controls 
  871.                    execution of the program.  If set true, the program will 
  872.                    terminate with all menus popped.
  873.  
  874.  
  875.    Menu Sequence - The following variables indicate the current status of the 
  876.    menus and work windows.  You can know what the current menu is and the 
  877.    current sequence of letter commands to get there.
  878.  
  879.      Variable      Description
  880.      ------------  -----------------------------------------------------------
  881.      TopCmdLtrs    (Type: string[NumOfMainMenus])  This is the counterpart of 
  882.                    Menu.CmdLtrs for the Top Line menu.  It holds the command 
  883.                    letters for the Top Line menu where character 1 corresponds 
  884.                    to the first main menu, character 2 to the second, etc.
  885.  
  886.      CmdSeq        (Type: SeqStrType)  This is the current sequence of letters 
  887.                    used to arrive at the current menu/window where the last 
  888.                    character is the last menu.  While in the work window, this 
  889.                    string is null.  Do not change this string.
  890.  
  891.      MoreCmdSeq    (Type: SeqStrType)  When performing a programmed pull down, 
  892.                    this is the sequence of letters yet to be executed in the 
  893.  
  894.  
  895.    Chapter 3, Data Structure                                           Page 15
  896.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  897.  
  898.  
  899.                    same order as CmdSeq.
  900.  
  901.      MPulled       (Type: byte)  This is the index of the current main menu 
  902.                    pulled.
  903.  
  904.      SPulled       (Type: byte)  This is the index of the current submenu 
  905.                    pulled.  If no submenu is pulled, this value is 0.
  906.  
  907.      HiLited       (Type: byte)  This is the row number of the currently 
  908.                    highlighted line.
  909.  
  910.      AccessedWorkWndw  (Type: boolean)  This is a handy flag available for 
  911.                    testing in your program.  If you are in the menus and you 
  912.                    run your custom routine with ProcPtr to set this false, the 
  913.                    next time the work window is accessed, this variable will 
  914.                    be true.
  915.  
  916.      AccessedMenus (Type: boolean)  This is a handy flag available for 
  917.                    testing in your program.  If you are in the work window and 
  918.                    set this false, the next time the menus are accessed, this 
  919.                    variable will be true.
  920.  
  921.      WorkWndwStep  (Type: byte)  This is the current step number assigned to 
  922.                    the work windows in PULLWORK.PAS.
  923.  
  924.      TopWorkWndwName (Type: WindowNames)  This is the name of the work window 
  925.                    to be selected for access or the current one on top.
  926.  
  927.      InWorkWndw    (Type: boolean = true)  When true, this typed constant 
  928.                    indicates if the program is in the work window.  It is 
  929.                    otherwise in the menus.
  930.  
  931.  
  932.    Addresses for Calls - The following pointers are used indirectly by 
  933.    indirect calls in PULL.TPU so that TP5 units can make calls forward outside 
  934. |  of a unit and also be compatible with TP4.  These are far addresses and are 
  935.    accessed as pointers with inline calls.
  936.  
  937.      Address variable      Unit.Procedure
  938.      --------------------  -------------------------
  939.      AddrGetUserPullStats  PullStat.GetUserPullStats
  940.      AddrGetOverrideStats  PullStat.GetOverrideStats
  941.      AddrWorkWndw          PullWork.WorkWndw
  942.      AddrCheckGlobalKeys   PullStat.CheckGlobalKeys
  943.      AddrKbdIdle           PullWork.KbdIdle
  944.  
  945.  
  946.    Untyped Key Constants - Several key constants have already been provided 
  947.    for frequently used keys.  Please refer to P5X-VAR.INC for the listing.
  948.  
  949.  
  950.    SUBMENU DECLARATIONS
  951.  
  952.    The following type and variables are used for the sub menus.  The variables 
  953.    are described in the order of their appearance in the file P5X-VAR.INC.  
  954.  
  955.  
  956.    Chapter 3, Data Structure                                           Page 16
  957.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  958.  
  959.  
  960.    The program was carefully planned so that main menu records would match 
  961.    that of the submenus.
  962.  
  963.  
  964.    Type - This type is used to structure variables in the heap for the 
  965.    submenus:
  966.  
  967.      Type          Description
  968.      ------------  -----------------------------------------------------------
  969.      SubMenus      This array allocates the total number of submenu records 
  970.                    needed for the heap.  They do not all have to be used.
  971.  
  972.    The Row/Col fields in the menu record for submenus default to zero so that 
  973.    PULL can locate them at run time for the slide-up configuration.  If they 
  974.    are set to non-zero values in PULLSTAT, then the menu will be located 
  975.    absolutely to the screen at (Row,Col).
  976.  
  977.    Variables - The following are the global variables used to allocate and 
  978.    configure the submenus:
  979.  
  980.      Variable      Description
  981.      ------------  -----------------------------------------------------------
  982.      SubMenu       (Type: ^MenuRecs) This is the pointer of the array of 
  983.                    submenu menu records in the heap.
  984.  
  985.      LastSubMenu   (Type: byte)  This is the index of the highest submenu 
  986.                    record number in use.  It is <=NumOfSubMenus.
  987.  
  988.  
  989.    Attributes - The following variables control the default attributes and 
  990.    border in all the submenus.  SameAttr is not permitted in byte types.
  991.  
  992.      Name          Type      Description
  993.      ------------  --------  -------------------------------------
  994.      SubMenuWattr  byte      entire Window contents.
  995.      SubMenuBattr  byte      submenu Border.
  996.      SubMenuHattr  byte      HiLite in submenu.
  997.      SubMenuLattr  byte      command Letters in submenu.
  998.      SubMenuCattr  byte      Comment line.
  999.      SubMenuBrdr   Borders   submenu Border style.
  1000.  
  1001.  
  1002.    MESSAGE LINE DECLARATIONS
  1003.  
  1004.    The following type, constant and variables are used to generate normal key 
  1005.    messages or error messages on the message line.  
  1006.  
  1007.    Type - The following type is the only one needed for error messages:
  1008.  
  1009.      Type           Description
  1010.      -------------  -----------------------------------------------------------
  1011.      ErrMsgStrType  This is the type used to size the length for all error 
  1012.                     messages based on ErrMsgSize.  Since they are usually 
  1013.                     short, they can be trimmed to the length of the longest 
  1014.                     one.
  1015.  
  1016.  
  1017.    Chapter 3, Data Structure                                           Page 17
  1018.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1019.  
  1020.  
  1021.  
  1022.    Constants - The following constants are given initial values to process the 
  1023.    messages on the message line.
  1024.  
  1025.      Constant           Description
  1026.      -----------------  ------------------------------------------------------
  1027.      CurrentMsgLineNum  (Type: word = 0)  This is the index of the current 
  1028.                         MsgLine displayed on the screen.
  1029.  
  1030.      EnableKeyStatus    (Type: boolean = true)  When true, the status of 
  1031.                         NumLock, ScollLock, and CapsLock will appear on the 
  1032.                         message line.
  1033.  
  1034.    Variables - The following variables allocate space for the messages in 
  1035.    global data and control the location of the messages and the key status 
  1036.    indicators:
  1037.  
  1038.      Variable      Description
  1039.      ------------  -----------------------------------------------------------
  1040.      MsgLine       (Type: array of CrtStrType)  This array allocates global 
  1041.                    data space for the messages.  If you intend to have several 
  1042.                    messages, you should consider making this data in the heap.
  1043.  
  1044.      ErrMsgLine    (Type: array of ErrMsgStrType)  This array allocates global 
  1045.                    data space for the error messages.  If you intend to have 
  1046.                    several messages, you should consider making this data in 
  1047.                    the heap.
  1048.  
  1049.      MsgLineRow    (Type: byte) This is the absolute row on which all messages 
  1050.                    and error messages are to appear. 
  1051.  
  1052.      CapsLockCol   (Type: byte) This is the column on the message line row on 
  1053.                    which the status indicators will appear.
  1054.  
  1055.    Attributes - The following variables control the attributes on the message 
  1056.    line.  SameAttr is not permitted in byte types.
  1057.  
  1058.      Name           Type  Description
  1059.      ------------   ----  ------------------------------
  1060.      ErrMsgAttr     byte  For error messages.
  1061.      KeyStatusAttr  byte  For the key status indicators.
  1062.      MsgLineAttr    byte  For the normal messages.
  1063.  
  1064.  
  1065.    HELP WINDOW DECLARATIONS
  1066.  
  1067.    The following types and variables are used to create context-sensitive help 
  1068.    windows.  
  1069.  
  1070.    Type - The following record is the only one needed for help windows:
  1071.  
  1072.      Type          Description
  1073.      ------------  -----------------------------------------------------------
  1074.      HelpWndwRec   This record is used to fully describe any help window.  
  1075.                    Each field is described below:
  1076.  
  1077.  
  1078.    Chapter 3, Data Structure                                           Page 18
  1079.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1080.  
  1081.  
  1082.  
  1083.                      FirstLine/LastLine - This is the first and last indexes 
  1084.                      in the HelpLines array that has the messages to appear in 
  1085.                      the help window.
  1086.  
  1087.                      LinesToShow - For now, the help window is a single page 
  1088.                      display and so this value is simply the number of lines 
  1089.                      from FirstLine to LastLine.
  1090.  
  1091.                      Row .. Cols - These variables locate and size the help 
  1092.                      window.  HelpBottomRow and HelpCharsPerLine are used to 
  1093.                      calculate these values.
  1094.  
  1095.                      The following variables control the attributes in the 
  1096.                      menus.  SameAttr is not permitted.
  1097.  
  1098.                        Battr - Border set by HelpWndwBattr
  1099.                        Wattr - entire Window contents set by HelpWndwWattr
  1100.  
  1101.                      Border - This is the border style used around the window 
  1102.                      and set to HelpWndwBrdr by default.
  1103.  
  1104.                      HWmodes - This is the window modes used to create the 
  1105.                      window on the screen.  HelpWndwModes is used to set this 
  1106.                      value by default.
  1107.  
  1108.                      MsgLineNum - This is the index number of the MsgLine to 
  1109.                      be displayed concurrently with the help window and is set 
  1110.                      by default to HelpMsgLineNum.
  1111.  
  1112.    Variables - The following variables allocate space for the records and help 
  1113.    lines in global data and control the location and appearance of the window:
  1114.  
  1115.      Variable        Description
  1116.      --------------  ---------------------------------------------------------
  1117.      HelpWndw        (Type: array of HelpWndwRec)  This array allocates global 
  1118.                      data space for the help windows.  If you intend to have 
  1119.                      several help window, you should consider making this data 
  1120.                      disk based.
  1121.  
  1122.      HelpLine        (Type: array of ErrMsgStrType)  This array allocates 
  1123.                      global data space for all the help lines.  If you intend 
  1124.                      to have several lines, you should consider making this 
  1125.                      data disk based.
  1126.  
  1127.      HelpBottomRow   (Type: byte)  This is the default row on which the bottom 
  1128.                      row of the help window is to appear.  This keeps help 
  1129.                      windows down lower.
  1130.  
  1131.      HelpWndwModes   (Type: byte)  This is the default used to set 
  1132.                      HelpWndw.HWmodes.  See WNDW.DOC for setting this 
  1133.                      variable.
  1134.  
  1135.      HelpMsgLineNum  (Type: byte)  This is the index of MsgLine for the 
  1136.                      message to appear concurrently with the help window.  The 
  1137.  
  1138.  
  1139.    Chapter 3, Data Structure                                           Page 19
  1140.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1141.  
  1142.  
  1143.                      index HelpML has been reserved as the default, but new 
  1144.                      ones can be used as well.
  1145.  
  1146.    Attributes - The following variables control the default attributes and 
  1147.    border in all the submenus.  SameAttr is not permitted in byte types.
  1148.  
  1149.      Name           Type      Description
  1150.      -------------  --------  -------------------------------------
  1151.      HelpWndwWattr  byte      entire Window contents.
  1152.      HelpWndwBattr  byte      help window Border.
  1153.      HelpWndwBrdr   Borders   help window Border style.
  1154.  
  1155.  
  1156.    DATA WINDOW / ENTRY DECLARATIONS
  1157.  
  1158.    The following types, constants and variables are used to create data entry 
  1159.    windows and work window data entry fields.
  1160.  
  1161.  
  1162.    Types - The following types are used to structure the data window/entry 
  1163.    records:
  1164.  
  1165.      Type            Description
  1166.      --------------  ---------------------------------------------------------
  1167.      TypeOfDataType  This enumerated type is used to indicate the type of data 
  1168.                      being processed.  Although the identifier list is 
  1169.                      intuitive, here is the list indicating its corresponding 
  1170.                      type:
  1171.  
  1172.                        Name       Type
  1173.                        ---------  ---------
  1174.                        Bytes      byte
  1175.                        Words      word
  1176.                        ShortInts  shortint
  1177.                        Integers   integer
  1178.                        LongInts   longint
  1179.                        Reals      real
  1180.                        UserNums   DataStrType
  1181.                        Chars      char
  1182.                        Strings    DataStrType
  1183.  
  1184.  
  1185.      SetNames        This enumerated type identifies character sets to be used 
  1186.                      for filtering each keystroke.  The names up to CharSet 
  1187.                      are reserved, but the list can be appended.
  1188.  
  1189.      EntrySetArray   This is the structure for allocating the data entry 
  1190.                      filter sets for the constant EntrySet.
  1191.  
  1192.      DataEntryRec    This record is used to fully describe any data entry.  
  1193.                      Each field is described below:
  1194.  
  1195.                        VarAddr - This is the absolute address where the 
  1196.                        contents of the entry is stored.
  1197.  
  1198.  
  1199.  
  1200.    Chapter 3, Data Structure                                           Page 20
  1201.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1202.  
  1203.  
  1204.                        TypeOfData - This declares the type of data located at 
  1205.                        VarAddr.  It is up to your programming skills to make 
  1206.                        sure that VarAddr and TypeOfData agree.
  1207.  
  1208.                        Row .. Col - For data windows, if these values default 
  1209.                        to (1,2) for the field location.  For data entry, this 
  1210.                        is the window-relative location of the field.
  1211.  
  1212.                        Field - This is the number of columns designated for 
  1213.                        the input and output to be displayed.
  1214.  
  1215.                        MaxField - This is the maximum number of characters 
  1216.                        that can appear in a field.  They can be less than or 
  1217.                        greater than Field which creates a flex-field entry.  
  1218.                        For strings, be sure that MaxField is no longer than 
  1219.                        the string destination or DataStrSize.
  1220.  
  1221.                        Decimals - For reals, this value is used to format the 
  1222.                        output output display which is Real:Field:Decimals.  If 
  1223.                        Decimals is negative then the format is Real:Field.
  1224.  
  1225.                        SetName - This is the name of the set used to filter 
  1226.                        the keystrokes into the field.  This variable is set by 
  1227.                        default according to TypeOfData.
  1228.  
  1229.                        TranslateProc - This procedure pointer is used to 
  1230.                        execute a procedure to intercept the keystroke for 
  1231.                        translation.  The default is nil.
  1232.  
  1233.                        CheckRangeProc - This procedure pointer is used to 
  1234.                        execute a procedure for checking the range or content 
  1235.                        of the entry before it is stored in the assigned 
  1236.                        variable.  The default is nil.
  1237.  
  1238.                        JustifyOutput - The justification of the output in data 
  1239.                        entry fields can be displayed by DisplayFields either 
  1240.                        right or left justified.  By default, numbers are right 
  1241.                        justified and strings left.
  1242.  
  1243.                        The following variables control the attributes in the 
  1244.                        menus.  SameAttr is not permitted.
  1245.  
  1246.                          Iattr - Input  default set by DataWndwIattr
  1247.                          Oattr - Output default set by DataWndwOattr
  1248.  
  1249.                        MsgLineNum - This is the index number of the MsgLine to 
  1250.                        be displayed concurrently with this entry during input.
  1251.  
  1252.                        HelpWndwNum - This is the index number of the HelpWndw 
  1253.                        record to be displayed when context-sensitive help is 
  1254.                        requested.
  1255.  
  1256.      DataWndwRec     This record is used to fully describe any data window.  
  1257.                      Each field is described below:
  1258.  
  1259.  
  1260.  
  1261.    Chapter 3, Data Structure                                           Page 21
  1262.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1263.  
  1264.  
  1265.                        Title - This is the title to appear centered on the top 
  1266.                        row of the border.  The default is ''.
  1267.  
  1268.                        DWrow / DWcol - If these values are the default zero, 
  1269.                        PULL will locate the window at run time for the slide-
  1270.                        under configuration.  Non-zero values will override 
  1271.                        PULL and locate the window absolute to the screen.
  1272.  
  1273.                        Battr - This is the attribute of the data window 
  1274.                        border.
  1275.  
  1276.                        Border - This is the border style of the border.
  1277.  
  1278.                        Entry - (Type: DataEntryRec) This is a record within 
  1279.                        the DataWndwRec that fully describes the field inside 
  1280.                        the window.
  1281.  
  1282.      DataWndws       This sets the structure for all of the data window 
  1283.                      records to be allocated in the heap.
  1284.  
  1285.      DataEntries     This sets the structure for all of the data entry records 
  1286.                      in a work/user window to be allocated in the heap.
  1287.  
  1288.      DataStrType     Combined with DataStrSize, this type will limit the size 
  1289.                      of strings that can be entered/read from any data entry.
  1290.  
  1291.      DataPadRec      This record conveniently groups all of the data needed 
  1292.                      for the Data Pad.  Each one of the fields is described 
  1293.                      below.
  1294.  
  1295.                        StoreMode - If true, the Data Pad will store the data 
  1296.                        to its destination variable, else the Data Pad reads 
  1297.                        the contents of the variable.
  1298.  
  1299.                        Valid - The result saved from the validity check for 
  1300.                        numbers is true if it passes.
  1301.  
  1302.                        DataStored - If the data passes the validity check, the 
  1303.                        range check, and is stored, this variable is set true 
  1304.                        which is later used to set TopMenu.Changed to true.
  1305.  
  1306.                        NewData - This flag is used internally to indicate an 
  1307.                        untampered entry has been displayed for editing.  Once 
  1308.                        edited, this value is false.
  1309.  
  1310.                        PullDW - This flag indicates that a pull-down data 
  1311.                        window is being used for data entry.
  1312.  
  1313.                        FieldIndex - This is the index of DataStr for the first 
  1314.                        character shown in the field.
  1315.  
  1316.                        CursorOfs - This is the offset from FieldIndex for the 
  1317.                        position of the cursor.
  1318.  
  1319.                        Hattr - The attribute for the HiLite used to move from 
  1320.  
  1321.  
  1322.    Chapter 3, Data Structure                                           Page 22
  1323.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1324.  
  1325.  
  1326.                        field to field in the work window or user window can be 
  1327.                        any attribute.  If SameAttr is used, only the cursor is 
  1328.                        moved and the output attribute remains unchanged.
  1329.  
  1330.                        ErrMsg - After a range check, if this value is zero, 
  1331.                        the entry value is in range.  If not, it is the number 
  1332.                        of the error message to be displayed.
  1333.  
  1334.                        Flex - If MaxField does not equal Field, this value is 
  1335.                        set to 1 to indicate a flex field.
  1336.  
  1337.                        Justify - This indicates the type of justification for 
  1338.                        the input and output display of the field.  Input is 
  1339.                        always left, but output can either be left or right.
  1340.  
  1341.                        TypeOfDataType - The last field in the data pad is the 
  1342.                        scratch pad for placing any type of data.  To access 
  1343.                        the data, use one of the following variant field 
  1344.                        identifiers:
  1345.  
  1346.                          Identifier Type
  1347.                          ---------- ---------
  1348.                          Bdata      Bytes
  1349.                          Wdata      Words
  1350.                          SIdata     ShortInts
  1351.                          Idata      Integers
  1352.                          Ldata      LongInts
  1353.                          Rdata      Reals
  1354.                          UNdata     UserNums
  1355.                          Cdata      Chars
  1356.                          Sdata      Strings
  1357.  
  1358.  
  1359.    Typed Constant - EntrySet is the array of the actual sets used for 
  1360.    filtering the keystrokes before being entered into the field.  Along with 
  1361.    each index name is the application of the set.  The sets up to CharSet are 
  1362.    reserved.  Other sets can be appended.
  1363.  
  1364.      Index name   Application
  1365.      -----------  -----------------------------------------
  1366.      UnsignedSet  For Bytes and Words
  1367.      SignedSet    For ShortInts, Integers, and LongInts
  1368.      RealSet      For Reals
  1369.      CharSet      For Chars, Strings and misc. entry
  1370.      HexSet       For UserNums and Hex
  1371.      FileNameSet  For DOS file names
  1372.      PathSet      For DOS full path file names
  1373.      MaskSet      For DOS full path file names with wildcard
  1374.  
  1375.    Variables - The following variables allocate space for data windows, data 
  1376.    entries, and the data pad: 
  1377.  
  1378.      Variable      Description
  1379.      ------------  ---------------------------------------------------------
  1380.      DWI           (Type: word)  Data Window Index used to save the current 
  1381.  
  1382.  
  1383.    Chapter 3, Data Structure                                           Page 23
  1384.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1385.  
  1386.  
  1387.                    data window record number currently in TopDataWndw.
  1388.  
  1389.      DEI           (Type: word)  Data Entry Index used to save the current 
  1390.                    data entry record number currently in TopEntry.
  1391.  
  1392.      TopDataWndw   (Type: DataWndwRec)  This is a copy of the record from the 
  1393.                    heap of the current DataWndwRec.  This saves code.
  1394.  
  1395.      TopEntry      (Type: DataEntryRec)  This is a copy of the record from the 
  1396.                    heap of the current DataEntryRec.  This saves code.
  1397.  
  1398.      DataWndw      (Type: ^DataWndws) This pointer accesses the array of 
  1399.                    data window records in the heap.
  1400.  
  1401.      DataEntry     (Type: ^DataEntry) This pointer accesses the array of 
  1402.                    data entry records in the heap.
  1403.  
  1404.      DataStr       (Type: DataStrType)  This is the actual string edited on 
  1405.                    the screen during an entry into a field.  The length of the 
  1406.                    string is limited by DataStrSize.
  1407.  
  1408.      DataStrL      (Type: byte)  This is the current string length of DataStr 
  1409.                    by accessing DataStr[0].
  1410.  
  1411.      DataPad       (Type: DataPadRec)  This is the data pad used to transfer 
  1412.                    data between the destination variable and the screen.
  1413.  
  1414.      AutoTab       (Type: boolean)  When set true for EnterSeq, the HiLite 
  1415.                    will advance to the next field automatically after entry.
  1416.  
  1417.      AutoNumLock   (Type: boolean)  For numerical entries, this flag will 
  1418.                    automatically turn on NumLock and is shown on the message 
  1419.                    line with the key status indicator.
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.    Chapter 3, Data Structure                                           Page 24
  1445.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1446.  
  1447.  
  1448.    A P P E N D I X  A :   M E M O R Y   A L L O C A T I O N
  1449.  
  1450.    This section covers the memory requirements for global data in the data 
  1451.    segment and dynamic data in the heap.  This will give you the figures on 
  1452.    how to estimate the memory needed for your program.
  1453.  
  1454.  
  1455.    CHOOSING GLOBAL VS. DYNAMIC
  1456.  
  1457.    As is, PULL uses both global and dynamic memory for records and messages.  
  1458.    The menus and data window/entry records are dynamic while the help window 
  1459.    and messages use global memory.  Depending on the needs of your application 
  1460.    program, you can change where these records are located by removing or 
  1461.    adding the ^ symbol, if you have the source code, along with the usual 
  1462.    HeapOK/GetMem instructions.
  1463.  
  1464.    PULLDEMO - In the demonstration, it was chosen to use the messages and help 
  1465.    windows as global memory since the program was so small.  In larger 
  1466.    programs that need more global data, these records can be shifted to 
  1467.    dynamic memory or even to disk.
  1468.  
  1469.  
  1470.    GLOBAL MEMORY
  1471.  
  1472.    Global Memory - The following values reflect both the approximate minimum 
  1473.    data requirements when global memory is a premium, and the allocation used 
  1474.    in PULL.TPU using the current configuration constants:
  1475.  
  1476.                                      Min    Demo
  1477.      Features                        Bytes  Bytes  Comments
  1478.      ------------------------------- -----  -----  -------------------
  1479.      Basic pull-down menus             652    652
  1480.      Submenus                           12     12
  1481.      Data window/entry, filter sets    579    675 
  1482.      Help windows                       34   4611  Used global in demo
  1483.      Messages                           16   1326  Used global in demo
  1484.                                      -----  -----
  1485.      Total allocation                 1293   7276
  1486.  
  1487.    Of course your application will vary, but these figures give you a good 
  1488.    estimate of the amount of memory being used.  The demo figures for the help 
  1489.    windows and message are higher because the text strings were placed in 
  1490.    global memory.
  1491.  
  1492.  
  1493.    DYNAMIC MEMORY
  1494.  
  1495.    Dynamic Variables - To alleviate using global data, dynamic variables are 
  1496.    used for permanent and temporary use.  The allocation for menus and data 
  1497.    window/entry records are permanent throughout the program.  Many other 
  1498.    procedures such as pulling down menus temporarily use the heap to perform 
  1499.    operations. 
  1500.  
  1501.    Permanent Variables - If the directives have been defined, the following 
  1502.    allocation can be calculated:
  1503.  
  1504.  
  1505.    Appendix A: Memory Allocation                                       Page 25
  1506.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1507.  
  1508.  
  1509.  
  1510.      Records       Calculation                                     Demo Bytes
  1511.      ------------  ----------------------------------------------  ----------
  1512.      Menus         SizeOf(TopMenu)*(NumOfMainMenus+NumOfSubMenus)   7664
  1513.      Data windows  SizeOf(TopDataWndw)*(NumOfDataWndws)              658
  1514.      Data entries  SizeOf(TopEntry)*(NumOfDataEntries)               240
  1515.  
  1516.    Again, this is just a general idea of what your program would allocate.  
  1517.    This is totally dependent on the configuration constants you choose.
  1518.  
  1519.    Temporary Variables - When pulling down menus, the underlays are accessed 
  1520.    in a serial fashion, so your calculations can be exact.  There is no need 
  1521.    to double the size of the heap needed as you would for random access.  For 
  1522.    a further discussion on dynamic memory allocation for windows, please refer 
  1523.    to the appendix in WNDWREF.DOC.
  1524.  
  1525.  
  1526.    CODE SIZE
  1527.  
  1528.    Code Size - PULL is also very frugal with with code.  Here is the 
  1529.    breakdown for code usage (this may vary slightly):
  1530.  
  1531.      Code Description                Bytes
  1532.      ------------------------------- -----
  1533.      Basic pull-down menus            4320
  1534.      Additional for submenus          1056
  1535.      Additional for data wndw/entry   3952
  1536.      Additional for help windows       704
  1537.      Additional for messages           880
  1538.                                      -----
  1539.      Total code                      10912
  1540.  
  1541.    Of course the TP5 smart compiler will optimize the code leaving out unused 
  1542.    procedures.  But this gives you a good idea of how small the code really 
  1543.    is!
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.    Appendix A: Memory Allocation                                       Page 26
  1567.    PULL Multi-level Pull-Down Menus              Reference Guide, Version 5.Xa
  1568.  
  1569.  
  1570.    A P P E N D I X  B :   E R R O R   M E S S A G E S
  1571.  
  1572.    PULL uses the same GOOF unit as WNDW does.  Should you make a mistake in 
  1573.    programming with windows or PULL,  the program will terminate with an error 
  1574.    message window on the CRT to reveal any problem.  The program terminates 
  1575.    through the GOOF unit which can be freely edited.
  1576.  
  1577.  
  1578.    WNDW
  1579.  
  1580.    The following error messages occur when a mistake has been made in creating 
  1581.    or controlling windows:
  1582.  
  1583.    "Not enough heap space" - The minimum heap size is too small.  Increase the 
  1584.    size as required in APPENDIX A of WNDW5XA.DOC.
  1585.  
  1586.    "Too many windows" - Tried to create more windows than MaxWndw allows.  
  1587.    Either remove windows or increase MaxWndw.
  1588.  
  1589.    "Too many virtual windows" - Tried to create more virtual windows than 
  1590.    MaxVirtualWndw allows.  Either remove windows or increase MaxVirtualWndw.
  1591.  
  1592.    "Perm window out of order" - Tried to create a PermMode window while a 
  1593.    normal window is the top window.  Remove or hide window before making a 
  1594.    permanent window.  Routinely, all PermMode windows are created first.
  1595.  
  1596.    "No window to remove" - Tried to remove the initial window Window0 which is 
  1597.    permanent.
  1598.  
  1599.    "Hidden window not found" - Tried to write to a hidden window that does not 
  1600.    exist.  Check for the correct name.
  1601.  
  1602.    "Virtual screen not found" - Tried to write to a virtual screen that does 
  1603.    not exist.  Check for the correct name.
  1604.  
  1605.    "Video page not available" - Tried to write to a video page that has not 
  1606.    been allocated or does not exist for the hardware as expected.  Be sure to 
  1607.    use MaxValidPage.
  1608.  
  1609.  
  1610.    PULL
  1611.  
  1612.    Only the following error message will occur in PULL:
  1613.  
  1614.    "A Submenu could not fit" - Tried to fit a menu that was too wide to fit in 
  1615.    the slide-up configuration.  Set LocationWarning false and test all 
  1616.    submenus to see if the slide-under alternative is acceptable.  If not, 
  1617.    override the default location by manually assigning the Row and Col values 
  1618.    of the menu record in GetUserPullStats.
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.    Appendix B: Error Messages                                          Page 27
  1628.